AbiPy v0.9.1 @IMEC¶
M. Giantomassi and the AbiPy group¶
IMEC seminar
June 10 2022 - Leuven, BE
- These slides have been generated using jupyter, nbconvert and revealjs
- The notebook can be downloaded from this github repo
- To install and configure the software, follow these installation instructions
Use the Space key to navigate through all slides and SHIFT + Space key to go back one slide.
What is AbiPy?¶
Python package for:¶
- Generating ABINIT input files automatically
- Post-processing results extracted from netcdf or text files
- Interfacing ABINIT with external tools such as vesta, wannier90, lobster, etc.
- Running ABINIT-specific workflows on laptops as well as on HPC clusters
Dependencies:¶
- Hard deps: pymatgen, netcdf4, matplotlib, plotly, numpy, scipy, pandas, ipython …
- Soft deps: ASE, phonopy, jupyter …
NB: AbiPy can be interfaced with other packages (e.g ASE, phonopy) via converters.
AbiPy design principles¶
- Extend the pymatgen code-base with ABINIT-specific objects
Layered structure designed for different use-cases:
Closely connected to the ABINIT executable:
- CPU-intensive algorithms performed by ABINIT (Fortran + MPI + OpenMP)
- Glue code implemented in python
ABINIT and AbiPy communicate through binary netcdf files
How to install AbiPy¶
Using conda and the conda forge channel (recommended):
conda install abipy --channel conda-forge
Since conda is not limited to python packages, one can install ABINIT in the same env with:
conda install abinit -c conda-forge
Using pip and python wheels:
pip install abipy --user
For further info see this installation howto
AbiPy documentation¶
In [9]:
%embed https://abinit.github.io/abipy/index.html
Out[9]:
Notebooks with examples and lessons¶
In [11]:
%embed https://nbviewer.jupyter.org/github/abinit/abitutorials/blob/master/abitutorials/index.ipynb
Out[11]:
Command line interface¶
- abiopen.py ➝ Open output files inside ipython or print/visualize file
- abistruct.py ➝ Operate on crystalline structures read from file
- abicomp.py ➝ Compare multiple files (i.e. convergence studies)
- abiview.py ➝ Quick visualization of output files
- abinp.py ➝ Generate input files for typical calculations
- abigui.py ➝ Start local web server with AbiPy GUI
Documentation¶
abistruct.py --helpfor manpageabistruct.py COMMAND --helpfor help aboutCOMMAND
HTML documentation available at http://abinit.github.io/abipy/scripts/index.html
abiopen.py
Print results stored in FILE (more than 45 file extensions supported)¶
In [12]:
!abiopen.py si_scf_GSR.nc --print # or -p
To produce a predefined set of matplotlib figures, use:¶
abiopen.py mgb2_kpath_FATBANDS.nc --expose --seaborn # or -e -sns
Replace --expose with --notebook to generate notebook with predefined python code¶
To start a web GUI for FILE, use the --panel option:¶
abiopen.py out_DDB --panel # or -pn if you prefer the short option.
Convert structure from netcdf format to CIF (abivars, xsf, poscar, qe, siesta, wannier90, json)¶
In [13]:
!abistruct.py convert si_scf_GSR.nc -f cif
Connect to the materials project database to find similar structures.¶
In [15]:
!abistruct.py mp_match si_scf_GSR.nc
Need to call anaddb to compute and visualize ph-bands and DOS from DDB?¶
abiview.py ddb ZnSe_hex_qpt_DDB --seaborn
Add --phononwebsite to visualize data on the phononwebsite by H. Miranda¶
To compare multiple structures:¶
In [16]:
!abicomp.py structure *.cif si_nscf_GSR.nc *_DDB
AbiPy API¶
AbiPy post-processing tools¶
Main entry point:
from abipy import abilab abifile = abilab.abiopen("filename.nc")
where filename.nc is a netcdf file (support also text files e.g. run.abo, run.log, out_DDB)
abifile is the AbiFile subclass associated to the given file extension:
- GSR.nc ➝ GsrFile
- HIST.nc ➝ HistFile
- More than 45 file extensions supported (see
abiopen.py --help)
AbiPy plots with matplotlib¶
In [17]:
gsr = abiopen("si_nscf_GSR.nc")
gsr.ebands.plot(with_gaps=True);
AbiPy plots with plotly¶
In [18]:
gsr.ebands.plotly(with_gaps=True); # obj.plot becomes obj.plotly
To upload the plotly figure to the chart studio server, use:¶
gsr.ebands.plotly(with_gaps=True, chart_studio=True);
Users can finally customize the AbiPy plot without changing the python code 🎉¶
Interactive 3d plots with plotly:¶
In [19]:
gsr.ebands.kpoints.plotly(title="k-path in 3d with plotly");
and, ça va sans dire, phonons from DDB with plotly:¶
In [20]:
znse_ddb = abilab.abiopen("ZnSe_hex_qpt_DDB")
phbst_file, phdos_file = znse_ddb.anaget_phbst_and_phdos_files()
phbands, phdos = phbst_file.phbands, phdos_file.phdos
phbands.plotly_with_phdos(phdos, units="cm-1");
To download a DDB file from the materials project database:¶
In [21]:
mgo_ddb = abilab.DdbFile.from_mpid("mp-1009129")
print(mgo_ddb)
Let's use the DdbRobot to compare phonons obtained with different ${\bf k}$-meshes and smearing values:¶
In [22]:
paths = [
"mgb2_888k_0.01tsmear_DDB",
"mgb2_888k_0.04tsmear_DDB",
"mgb2_121212k_0.01tsmear_DDB",
"mgb2_121212k_0.04tsmear_DDB",
]
paths = [os.path.join(abidata.dirpath, "refs", "mgb2_phonons_nkpt_tsmear", f)
for f in paths]
robot = abilab.DdbRobot()
for path in paths:
robot.add_file(path, path)
In [23]:
# Define function to change labels:
func = lambda ddb: "nkpt: %s, tsmear: %.2f" % (
ddb.header["nkpt"], ddb.header["tsmear"])
robot.remap_labels(func)
robot
Out[23]:
Now we can build a dataframe with the most important parameters:¶
In [24]:
robot.get_params_dataframe()
Out[24]:
and check that all DDBs have been computed with the same crystalline structure:¶
In [25]:
robot.get_lattice_dataframe()
Out[25]:
To analyze the effect of k-sampling/smearing on the vibrational properties:¶
In [26]:
# Invoke anaddb and store results
r = robot.anaget_phonon_plotters(nqsmall=2)
r.phbands_plotter.gridplot_with_hue("tsmear", with_dos=True);
How to run AbiPy Flows¶
⚠️ There are two different workflow infrastructures:¶
Internal AbiPy implementation (abipy.flowtk modules):¶
- ✅ Lightweigth, no database required
- ✅ Designed for rapid prototyping and/or for supporting advanced ABINIT capabilities
- ❌ No explicit support for high-throughput (HT) applications.
AbiFlows package (requires Fireworks and MongoDB database)¶
- ✅ HT-oriented: use MongoDB to store workflow status and results for further analysis
- ✅ High-level API designed for HT applications (e.g. phonon calculations for the materials project)
- ❌ Not all the flowtk workflows are immediately available in AbiFlows.
Here, we mainly discuss the abipy.flowtk API.
In order to run a Flow, we need two configurations files:¶
scheduler.yml providing:
- scheduler parameters such as days, hours, minutes, max_njobs_inqueue, max_ncores_used, …
manager.yml providing:
- list of shell commands to be executed before running ABINIT
- list of modules to load
- options for the queue manager (bluegene, moab, pbspro, sge, shell, slurm, torque)
See this page for examples or use the abidoc.py script and the syntax:
- abidoc.py scheduler
- abidoc.py manager
- abidoc.py manager slurm
One usually start by generating an AbinitInput for GS:¶
In [27]:
def make_scf_input(ecut=2, ngkpt=(4, 4, 4)):
"""
Generate an `AbinitInput` to perform GS calculation for AlAs.
Args:
ecut: Cutoff energy in Ha.
ngkpt: k-mesh divisions
Return:
`AbinitInput` object
"""
gs_inp = abilab.AbinitInput(structure="AlAs.cif",
pseudos=["13al.pspnc", "33as.pspnc"])
# Set the value of the Abinit variables needed for GS runs.
gs_inp.set_vars(
nband=4,
ecut=ecut,
ngkpt=ngkpt,
nshiftk=4,
shiftk=[0.0, 0.0, 0.5, # This gives the usual fcc Monkhorst-Pack grid
0.0, 0.5, 0.0,
0.5, 0.0, 0.0,
0.5, 0.5, 0.5],
tolvrs=1.0e-10,
)
return gs_inp
Inside the notebook, one gets the HTML representation with links to the documentation:¶
In [28]:
make_scf_input()
Out[28]:
From an AbiniInput one can easily build more complicate workflows:¶
In [29]:
def build_flow_alas_phonons():
"""
Build and return a Flow to compute the dynamical matrix on a (2, 2, 2) qmesh
as well as DDK and Born effective charges.
The final DDB with all perturbations will be merged automatically and placed
in the Flow `outdir` directory.
"""
from abipy import flowtk
scf_input = make_scf_input(ecut=6, ngkpt=(4, 4, 4))
return flowtk.PhononFlow.from_scf_input("flow_alas_phonons", scf_input,
ph_ngqpt=(2, 2, 2), with_becs=True)
Abipy will call Abinit to get the list of DFPT perturbations and…¶
In [30]:
flow_phbands = build_flow_alas_phonons()
flow_phbands.get_graphviz()
Out[30]:
How to run calculations?¶
The simplest way to start the scheduler from the shell is via the syntax:
run_elastic.py --scheduler # -s for the short option
For non-trivial Flows, we suggest to put the scheduler in background and use nohup
so that we can disconnect from the shell session without killing the scheduler.
nohup run_elastic.py --s > log 2> err &
Obviously, it is possible to submit a Slurm script that executes the script on the compute note with 1 core.
To interact with the Flow, one can also use the abirun.py script, e.g:
abirun.py FLOWDIR status
Selected examples of AbiPy Flows¶
ElasticWork¶
This flow computes:¶
- the rigid-atom elastic tensor
- the rigid-atom piezoelectric tensor (insulators only)
- the internal strain tensor
- the atomic relaxation corrections to the elastic and piezoelectric tensor
Python example¶
scf_input = make_scf_input() # Build input for GS calculation
elast_work = flowtk.ElasticWork.from_scf_input(scf_input,
with_relaxed_ion=True,
with_piezo=True)
Dependency Graph:¶
- Indipendent perturbations are computed in parallel with optimized MPI-params.
- Restart capabilities (e.g. timeout limit) and error handlers
- Intermediate DDB files are automatically merged.
- Final DDB file automatically produced in the outdata directory of the Work.
Effective masses with DFPT¶
This flow performs:¶
- GS-SCF run followed by NSCF run with k-path to locate band edges automatically
Compute $\epsilon^{\alpha\beta}_{n\bf{k}}$ and the effective mass tensor at the band edges using $|u_{n\mathbf{k}}\rangle$, and the k-derivatives $|u_{n\mathbf{k}}^\alpha\rangle$ $H^\alpha_{\mathbf{k}}$, $H^{\alpha\beta}_{\mathbf{k}}$
For the formalism, see J. Laflamme Janssen, et. al. Phys. Rev. B 93, 205147
- 1260 systems computed as a preliminary step for polaron studies
Python API:¶
flow = flowtk.Flow("flow_effmass_dfpt")
# Build input for GS SCF calculation.
scf_input = make_scf_input()
# This object implements all the worflow logic
from abipy.flowtk.effmass_works import EffMassAutoDFPTWork
work = EffMassAutoDFPTWork.from_scf_input(scf_input)
flow.register_work(work)
Workflows do not necessarily imply HT applications¶
- Sometimes, we need to address rather technical/fundamental questions
- For instance, one may ask whether the treatment of the dipole interaction is enough to obtain an accurate interpolation of the e-ph scattering potentials
- Answering this question required hundreds of DFPT + WFQ + EPH calculations along a very dense q-path (300 points):
- See G. Brunin's talk and PRL 125, 136601 (2020), PRB 102, 094308 (2020)
We used this AbiPy script to automate most of the steps:¶
NB: This is a simplified version with just 2 q-points in the path. In our work, we used 278 points.